Skip to content

chore: update openapi specs #6201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 14 commits into from
Jul 18, 2025
Merged

chore: update openapi specs #6201

merged 14 commits into from
Jul 18, 2025
+3,941 −1,297

Conversation

Jiloc
Copy link
Contributor

@Jiloc Jiloc commented Jun 13, 2025 •
edited
Loading

Description

This PR significantly updates and expands the openapi.yaml specification for the Stacks node RPC API. It adds definitions for numerous previously undocumented V2 and V3 endpoints, refactors common parameters into reusable components for consistency, and enhances existing endpoint definitions with more accurate details, schemas, and examples.

Key changes include:

  • All known RPC endpoints, including those from issue [Docs] Complete documentation of the node RPC-API #4551, are now documented.
  • Fixed numerous outdated endpoints with incorrect/missing/nonexistent parameters and return types.
  • The openapi.yaml has been broken down into reusable components for schemas, parameters, and examples, located in the new docs/rpc/components/ directory. All JSON schemas were converted to YAML.
  • Validation: A redocly.yaml configuration has been added, and the entire specification now passes the redocly lint check.

Applicable issues

Additional info (benefits, drawbacks, caveats)

Checklist

  • Test coverage for new or modified code paths
  • Changelog is updated
  • Required documentation changes (e.g., docs/rpc/openapi.yaml and rpc-endpoints.md for v2 endpoints, event-dispatcher.md for new events)
  • New clarity functions have corresponding PR in clarity-benchmarking repo
  • New integration test(s) added to bitcoin-tests.yml

@Jiloc Jiloc requested review from a team as code owners June 13, 2025 15:44
@Jiloc Jiloc self-assigned this Jun 13, 2025
@Jiloc Jiloc moved this to Status: In Review in Stacks Core Eng Jun 13, 2025
@Jiloc Jiloc added this to the 3.1.0.0.13 milestone Jun 13, 2025
@Jiloc Jiloc added the documentation Requires new or updates to our documentation label Jun 13, 2025
@wileyj
Copy link
Collaborator

wileyj commented Jun 13, 2025

would it be possible to also address this issue in this PR?
#5214

@wileyj wileyj requested a review from cylewitruk June 13, 2025 17:12
@wileyj
Copy link
Collaborator

wileyj commented Jun 13, 2025

tagging @cylewitruk since #4551 was his idea

@Jiloc
Copy link
Contributor Author

Jiloc commented Jun 16, 2025

would it be possible to also address this issue in this PR? #5214

I'll open a separate PR for that!

@aldur aldur requested a review from wileyj June 17, 2025 15:17
wileyj
wileyj previously approved these changes Jun 18, 2025
View reviewed changes
Copy link
Collaborator

@wileyj wileyj left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@kantai kantai moved this from Status: In Review to Status: 💻 In Progress in Stacks Core Eng Jun 24, 2025
@wileyj wileyj self-requested a review June 24, 2025 14:54
@wileyj wileyj requested a review from a team June 25, 2025 14:39
@wileyj wileyj moved this from Status: 💻 In Progress to Status: In Review in Stacks Core Eng Jun 25, 2025
@wileyj
Copy link
Collaborator

wileyj commented Jun 26, 2025

pending resolution of the the openapi validation, this seems fine

@obycode obycode modified the milestones: 3.1.0.0.13, 3.1.0.0.14 Jul 1, 2025
@kantai kantai moved this from Status: In Review to Status: 💻 In Progress in Stacks Core Eng Jul 2, 2025
@kantai kantai moved this from Status: 💻 In Progress to Status: In Review in Stacks Core Eng Jul 2, 2025
@Jiloc Jiloc mentioned this pull request Jul 4, 2025
Merged
5 tasks
@Jiloc Jiloc requested a review from a team as a code owner July 8, 2025 10:17
@Jiloc Jiloc requested a review from a team as a code owner July 8, 2025 16:30
@Jiloc
Copy link
Contributor Author

Jiloc commented Jul 9, 2025

@wileyj note that in the latests changes I also moved the validation workflow to ci.yml from stacks-core-tests.yml. The step was gated by the [CI / Create Test Cache / Test Archive (pull_request)] step that isn't actually correlated

@wileyj
Copy link
Collaborator

wileyj commented Jul 9, 2025 •
edited
Loading

@wileyj note that in the latests changes I also moved the validation workflow to ci.yml from stacks-core-tests.yml. The step was gated by the [CI / Create Test Cache / Test Archive (pull_request)] step that isn't actually correlated

hmm, i see the reasoning but i think it's better to keep under stacks-core-tests. otherwise, without some extra conditionals checking that the stacks-core-tests job was successful, this step will run every time - even if tests or other steps/jobs are failing.

it's not a bad thing necesarily (just adds noise), i just think it's better suited as part of the stacks-core-tests workflow. i'm less concerned that the create-test-cache workflow is gating this - if that fails, openapi validation shouldn't even run.

Otherwise, i think the changes still look good - just have to reach consensus on where to run it (along with the composite workflow merge)

@Jiloc
Copy link
Contributor Author

Jiloc commented Jul 11, 2025

@wileyj note that in the latests changes I also moved the validation workflow to ci.yml from stacks-core-tests.yml. The step was gated by the [CI / Create Test Cache / Test Archive (pull_request)] step that isn't actually correlated

hmm, i see the reasoning but i think it's better to keep under stacks-core-tests. otherwise, without some extra conditionals checking that the stacks-core-tests job was successful, this step will run every time - even if tests or other steps/jobs are failing.

it's not a bad thing necesarily (just adds noise), i just think it's better suited as part of the stacks-core-tests workflow. i'm less concerned that the create-test-cache workflow is gating this - if that fails, openapi validation shouldn't even run.

Otherwise, i think the changes still look good - just have to reach consensus on where to run it (along with the composite workflow merge)

I moved it back in e858b09

@codecov Codecov
Copy link

codecov bot commented Jul 12, 2025 •
edited
Loading

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 76.08%. Comparing base (32461ef) to head (48ec30c).
Report is 20 commits behind head on develop.

❌ Your project status has failed because the head coverage (76.08%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files 
@@             Coverage Diff             @@
##           develop    #6201      +/-   ##
===========================================
- Coverage    76.77%   76.08%   -0.69%     
===========================================
  Files          545      545              
  Lines       347417   347417              
  Branches       323      323              
===========================================
- Hits        266719   264332    -2387     
- Misses       80690    83077    +2387     
  Partials         8        8

see 272 files with indirect coverage changes

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 32461ef...48ec30c. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

wileyj
wileyj previously approved these changes Jul 14, 2025
View reviewed changes
Copy link
Collaborator

@wileyj wileyj left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with the composite merged and working, i think this one is also ready to go

@aldur aldur requested a review from fabergat July 16, 2025 15:00
@Jiloc Jiloc requested a review from wileyj July 17, 2025 09:32
@Jiloc Jiloc mentioned this pull request Jul 17, 2025
Open
5 tasks
fabergat
fabergat approved these changes Jul 17, 2025
View reviewed changes
Copy link

@fabergat fabergat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@github-project-automation github-project-automation bot moved this from Status: In Review to Status: 💻 In Progress in Stacks Core Eng Jul 18, 2025
@Jiloc Jiloc added this pull request to the merge queue Jul 18, 2025
Merged via the queue into stacks-network:develop with commit dd838f1 Jul 18, 2025
239 of 242 checks passed
@Jiloc Jiloc deleted the chore/update-openapi-spec branch July 18, 2025 13:20
@github-project-automation github-project-automation bot moved this from Status: 💻 In Progress to Status: ✅ Done in Stacks Core Eng Jul 18, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@rdeioris rdeioris rdeioris approved these changes

@fabergat fabergat fabergat approved these changes

@cylewitruk cylewitruk Awaiting requested review from cylewitruk

@wileyj wileyj Awaiting requested review from wileyj

Assignees

@Jiloc Jiloc

Labels
documentation Requires new or updates to our documentation
Projects
Stacks Core Eng
Status: Status: ✅ Done
Milestone
3.2.0.0.0
Development

Successfully merging this pull request may close these issues.
5 participants
@Jiloc @wileyj @rdeioris @fabergat @obycode